docs: add Syntax component for inline language-specific identifiers by notowen333 · Pull Request #2751 · strands-agents/harness-sdk

notowen333 · 2026-06-12T15:20:02Z

Description

Adds a new <Syntax> MDX component that renders language-appropriate identifiers (Python snake_case vs TypeScript camelCase) inline based on the global language selector. This eliminates the manual pattern of spelling out both variants in shared prose (e.g., `snake_name` / `camelName`).

Motivation

Documentation pages frequently reference SDK identifiers in prose that sits outside language-specific tabs. Previously this meant writing both names inline, which was verbose, inconsistent across pages, and didn't react to the reader's language preference. The new component provides a single source of truth per identifier that switches live with the language toggle.

Public API Changes

No public API changes — this is a documentation infrastructure addition.

Component API

<Syntax py="conversation_manager" ts="conversationManager" />
<Syntax py=".as_tool()" ts=".asTool()" />
<Syntax py="strict=True" ts="strict: true" code={false} />

Prop	Type	Default	Description
`py`	string	required	Python identifier
`ts`	string	required	TypeScript identifier
`code`	boolean	`true`	Wrap in `<code>` (false for plain text)

Implementation

site/src/components/Syntax.astro — custom element <syntax-switch> with an idempotent inline script that reads the same localStorage key as the existing language tabs
Auto-imported via astro-auto-import so no explicit imports needed in MDX
Reacts to tab clicks (.lang-option delegated listener) and cross-tab storage events

Scope

Converted ~26 instances across 16 documentation pages
Updated agent skills (writer, reviewer, audit) to teach future authors about the component
Updated references (mdx-authoring.md, voice-guide.md) and contributor docs

Type of Change

Documentation update

Testing

Full npx astro build passes (655 pages, 0 broken links)
Verified every TypeScript identifier against SDK source at sdk-typescript/strands-ts/src/
Manual browser testing confirms live language switching

Checklist

I have read the CONTRIBUTING document
I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works
My change is focused and reasonably small; I have split unrelated work into separate PRs
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Introduces a new auto-imported <Syntax py="..." ts="..." /> component that renders the correct identifier based on the global language toggle. Replaces manual patterns like "`snake_name` / `camelName`" in shared prose with a single reactive element. - New Syntax.astro component (custom element + inline script) - Auto-imported via astro-auto-import plugin - Converted ~26 instances across 16 doc pages - Updated agent skills, references, and contributor docs

github-actions · 2026-06-12T15:40:05Z

Assessment: Comment

Clean, well-scoped documentation addition. I spot-checked the converted identifiers against the SDK source (recordDirectToolCall, asTool, retryStrategy, structuredOutputSchema, ModelThrottledError, invocation_state) and they all match. The companion docs/skills updates do a good job teaching future authors when to reach for <Syntax> vs <Tabs>. One point worth discussing before merge (graceful degradation / SSR), plus a couple of minor cleanups.

Review themes

Rendering / SEO (important): The component renders empty markup server-side and fills text only via JS, so no-JS readers and crawlers see a blank gap, with a brief empty-flash on first paint. The sibling LangCodeBlock already solves this by SSR-ing both variants and toggling with CSS — worth mirroring. (inline)
Maintainability (suggestion): The localStorage key + default-language constants are now copied across four files; a shared module would prevent drift. (inline)
Dead attribute (suggestion): data-code is set but never read. (inline)
Verification: Identifier accuracy confirmed against source; textContent (not innerHTML) keeps it XSS-safe; the single-run init guard is fine given the site doesn't use Astro view transitions.

Nice quality-of-life improvement for the docs — the live language switching on inline identifiers is a real readability win.

Address review feedback: - Render both Python and TypeScript content at build time with CSS-driven visibility (no empty flash, crawlable by default) - Remove unused data-code attribute - JS now toggles display:inline/none instead of setting textContent

github-actions · 2026-06-12T15:54:54Z

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Changed pages:

Updated at: 2026-06-12T20:13:03.614Z

github-actions · 2026-06-12T15:56:27Z

Re-reviewed after 921bd6d (fix(syntax): server-render both variants, remove dead data-code attr). Both actionable items from the last pass are resolved:

✅ SSR/SEO/graceful degradation — Both variants now render server-side (<code data-lang="Python"> / <code data-lang="TypeScript">), with CSS hiding Python by default and JS toggling display. No-JS readers and crawlers now see the identifier, and the empty-content flash is gone. This matches the LangCodeBlock pattern cleanly.
✅ Dead data-code attribute — Removed.

The remaining note (extracting the duplicated STORAGE_KEY/DEFAULT_LANG into a shared module) was explicitly non-blocking, so deferring it is a reasonable call — though a follow-up would be nice given the key is now repeated in four places.

Updated assessment: Approve. Nice, quick turnaround. 👍

lizradway · 2026-06-12T18:53:44Z

as a follow up, might be worth going through and ensuring that we actually have bilingual values for all of the code var references. Conversation management concept page is a good example of this; a lot of vars are cited as code, but do not have python/TS verisons.

lizradway · 2026-06-12T18:55:00Z

we can also probably remove a lot of the "In TypeScript, ModelRetryStrategy is the abstract base class. Use DefaultModelRetryStrategy for the standard configurable strategy:" type things now ! as a follow up

github-actions · 2026-06-12T19:07:21Z

Re-reviewed after c3c0b966 (docs: replace Syntax section with agent skills guide, fix count_tokens):

✅ Per @lizradway's note, the site-facing "Inline language-specific names" section was removed from documentation.mdx — <Syntax> is a site-development concern, so keeping its usage guidance in .agents//skills (not on the public page) is the right call. The replacement "Agent skills" section fits the page's contributor scope well.
✅ The new count_tokens() / countTokens() conversion in context-offloader.mdx checks out against source (model.countTokens in strands-ts, model.count_tokens in strands-py).

The two broader follow-up items from the maintainer (auditing all code-styled vars for missing bilingual variants, and trimming now-redundant "In TypeScript..." prose) are reasonable to handle separately and aren't blocking here.

Assessment unchanged: Approve. All review threads resolved.

…ntrib - Rename `code` prop to `plain` (default false) so the common case needs no prop and the rare case reads naturally as `plain` - Add proper Agent Skills section to contributing page with table and usage examples - Convert model.count_tokens() to <Syntax> in context-offloader

github-actions · 2026-06-12T20:11:51Z

Re-reviewed after 34bcf86 (refactor(syntax): rename code prop to plain, add skills section to contrib):

✅ code → plain rename is a clean API improvement. Flipping to a positive-default boolean (plain = false) where the prop name describes the non-default behavior is more idiomatic than the previous inverted code = true. The component logic correctly maps plain → <span> and the default → <code>.
✅ Consistency verified — all 32 <Syntax> call sites checked: no stale code= props remain, and the docs/skills references (mdx-authoring.md, voice-guide.md, the three docs-* skills) all describe the new plain prop with no leftover code mentions.
ℹ️ The three expression call sites (strict=True, record_direct_tool_call=False, should_truncate_results=True) now render as inline <code> rather than plain text. That's the right call — they're code expressions, so code styling fits.

Assessment unchanged: Approve. Clean refactor with consistent rollout.

@lizradway

…anual variants Addresses @lizradway's review on strands-agents#2752: replace manually-spelled '(Python)/(TypeScript)' prose and the duplicated Configuration <Tabs> table with the <Syntax py=... ts=... /> component (owen's strands-agents#2751), per the mdx-authoring convention. - Stdio Mode prose: ask="stdio" / ask: 'stdio' -> <Syntax> - Custom UI Callback: drop 'In Python, both sync and async...' (the code tab already shows the language-specific form) - Configuration: collapse the two-tab Python/TypeScript table into a single table whose differing identifiers use <Syntax> - Trust Mode + Related Topics + Custom Evaluate prose: agent.state / appState and the True/'y'/'yes' approval spelling now use <Syntax> Merged main to pick up the <Syntax> component (strands-agents#2751) and the merged strands-agents#2750 code.

github-actions Bot added the size/m label Jun 12, 2026

notowen333 had a problem deploying to manual-approval June 12, 2026 15:20 — with GitHub Actions Error

notowen333 requested a deployment to manual-approval June 12, 2026 15:20 — with GitHub Actions Waiting

github-actions Bot added enhancement New feature or request documentation Documentation changes, improvements, additions, content updates, site improvements, examples, guides labels Jun 12, 2026

notowen333 marked this pull request as ready for review June 12, 2026 15:33

notowen333 temporarily deployed to auto-approve June 12, 2026 15:33 — with GitHub Actions Inactive

github-actions Bot added the strands-running label Jun 12, 2026

github-actions Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread site/src/components/Syntax.astro Outdated

github-actions Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread site/src/components/Syntax.astro Outdated

github-actions Bot reviewed Jun 12, 2026

View reviewed changes

Comment thread site/src/components/Syntax.astro

github-actions Bot removed the strands-running label Jun 12, 2026

github-actions Bot added size/m and removed size/m labels Jun 12, 2026

notowen333 temporarily deployed to auto-approve June 12, 2026 15:49 — with GitHub Actions Inactive

github-actions Bot added the strands-running label Jun 12, 2026

github-actions Bot removed the strands-running label Jun 12, 2026

lizradway reviewed Jun 12, 2026

View reviewed changes

Comment thread site/src/content/docs/contribute/contributing/documentation.mdx Outdated

lizradway reviewed Jun 12, 2026

View reviewed changes

Comment thread site/src/content/docs/user-guide/concepts/model-providers/google.mdx

github-actions Bot added size/m and removed size/m labels Jun 12, 2026

notowen333 had a problem deploying to auto-approve June 12, 2026 19:04 — with GitHub Actions Error

github-actions Bot added the size/m label Jun 12, 2026

notowen333 temporarily deployed to auto-approve June 12, 2026 19:06 — with GitHub Actions Inactive

github-actions Bot removed the strands-running label Jun 12, 2026

lizradway reviewed Jun 12, 2026

View reviewed changes

Comment thread site/src/content/docs/contribute/contributing/documentation.mdx

lizradway previously approved these changes Jun 12, 2026

View reviewed changes

notowen333 dismissed lizradway’s stale review via 34bcf86 June 12, 2026 20:03

github-actions Bot added size/m and removed size/m labels Jun 12, 2026

notowen333 temporarily deployed to auto-approve June 12, 2026 20:05 — with GitHub Actions Inactive

zastrowm approved these changes Jun 12, 2026

View reviewed changes

notowen333 temporarily deployed to auto-approve June 12, 2026 20:05 — with GitHub Actions Inactive

lizradway approved these changes Jun 12, 2026

View reviewed changes

github-actions Bot added the strands-running label Jun 12, 2026

github-actions Bot removed the strands-running label Jun 12, 2026

notowen333 merged commit 40e93c0 into strands-agents:main Jun 12, 2026
12 checks passed

This was referenced Jun 15, 2026

feat: add memory injection #2797

Merged

chore: add CLAUDE.md files #2809

Merged

feat: add default for memory extraction trigger #2811

Merged

fix: mark internal memory functions as private #2817

Merged

agent-of-mkmeral mentioned this pull request Jun 16, 2026

docs: add Python tabs to HumanInTheLoop intervention docs #2752

Merged

6 tasks

This was referenced Jun 16, 2026

feat: add durable identifiers to messages #2836

Open

feat: telemetry for memory manager #2858

Open

feat: add local memory store #2859

Open

This was referenced Jun 25, 2026

docs: improve agent guidance #2959

Draft

docs: add TESTING.md for python #2961

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add Syntax component for inline language-specific identifiers#2751

docs: add Syntax component for inline language-specific identifiers#2751
notowen333 merged 4 commits into
strands-agents:mainfrom
notowen333:docs-syntax-update

notowen333 commented Jun 12, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

github-actions Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Uh oh!

lizradway commented Jun 12, 2026

Uh oh!

lizradway commented Jun 12, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

notowen333 commented Jun 12, 2026

Description

Motivation

Public API Changes

Component API

Implementation

Scope

Type of Change

Testing

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

github-actions Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Preview Ready

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Uh oh!

lizradway commented Jun 12, 2026

Uh oh!

lizradway commented Jun 12, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Jun 12, 2026 •

edited

Loading